Server Watch Plugin SDK Date: 6 Feb 2004
Release: 1.0
Main Page | Class Hierarchy | Class List | File List | Class Members | File Members | Related Pages

swplugindll.h File Reference


Detailed Description

The file defines the C functions that must be implemented by each plugin. They form the interface that allows Server Watch to communicate with your plugin.

Fill in details.

See also:
SWPluginServerStruct

Go to the source code of this file.

Introspective Functions

Server Watch needs to know what functionality is and is not supported by each plugin, because not every plugin will support all of Server Watch's built in functionality. In order for Server Watch to get this information, the plugin must implement a set of introspection functions that allow Server Watch to ask the plugin about itself, and what functionality it supports.

enum  FunctionalSwitch {
  AUX_STAT, PORT_DISABLED, PORT_HIDDEN, BUDDIES,
  JOIN, ADDRESS_DISABLED
}
bool DoYouSupport (const FunctionalSwitch eType)

Loading and Unloading the Plugin

The plugin is given the oportunity to initialize any information global to the plugin when it is loaded as well as clean itself up before it closes through the implementation of these functions.

SWRESULT LoadPlugin ()
SWRESULT UnloadPlugin ()

Creating and Destroying a Server

Functions that will be called when servers are created or destroyed

SWRESULT InitServer (SWPluginServerStruct *pThisServer)
SWRESULT CleanupServer (SWPluginServerStruct *pThisServer)

Server Actions

These are a set of functions triggered directly by user action.

SWRESULT Ping (SWPluginServerStruct *pThisServer)
SWRESULT JoinServer (SWPluginServerStruct *pThisServer)

Menu Actions

Allows a plugin to display special context menus selections in key areas of Server Watch.

SWRESULT CreateMenu (SWPluginServerStruct *pThisServer, ISWPluginMenu *pPluginMenu)


Enumeration Type Documentation

enum FunctionalSwitch
 

The elements of this enum represent the possible things that a plugins could be queried about support for

Enumeration values:
AUX_STAT  Whether or not the plugin uses the auxiliary stat. If it does, then the title should also be defined.
PORT_DISABLED  Whether or not the port control should be disabled.
PORT_HIDDEN  Whether or not the port should be hidden.
BUDDIES  Whether or not the buddies dialog should be displayed.
JOIN  Whether or not the join dialog should be displayed.
ADDRESS_DISABLED  Whether or not the address control should be disabled.


Function Documentation

SWRESULT LoadPlugin  ) 
 

Called by Server Watch when the plugin is initially loaded.

This will be the first function called on the plugin and is a good place to initialize any global plugin data. It is perfectly valid to do nothing but return SW_OK if you do not need to do anything in this function.

Return values:
SW_OK Return this if the processing within this function was successful
SW_FAIL Return this if the processing within this function failed

SWRESULT UnloadPlugin  ) 
 

Called by Server Watch when the plugin is unloaded (shut down).

This is an appropriate place to cleanup any global plugin data that may have been created during the regular processing of the plugin. It is perfectly valid to do nothing but returns W_OK if you do not need to do anything in this function.

Return values:
SW_OK Return this if the processing within this function was successful
SW_FAIL Return this if the processing within this function failed

bool DoYouSupport const FunctionalSwitch  eType  ) 
 

Called by Server Watch in order to ascertain what functionality it supports.

Note:
Remember that future versions of the Server Watch API will likely support new functionality, so if you return false for all the types the plugin does not support, including those that have not been defined yet, then your code will be substantially more resilient to those changes.
Parameters:
eType The functionality that Server Watch is querying about.
Return values:
true The specified functionality is supported by the plugin
false The specified functionality is not supported by the plugin

SWRESULT InitServer SWPluginServerStruct pThisServer  ) 
 

Called whenever a new server is created by the user or by Server Watch at load time (called for each saved server). This is where any of your per-server initialization should be located.

If you need to store your own data related to this server that cannot be stored in either the ISWServerData or ISWServerSettings classes, you can create your own structure or class, and set SWPluginServerStruct's pCustomData variable to point to that structure or class. This object will then be passed to all of the plugin functions that require knowledge of specific server data. You won't need to store it yourself, but you will need to cleanup that structure or class on subsequent calls to CleanupServer().

Parameters:
pThisServer A SWPluginServerStruct that contains the information related to this server.
Return values:
SW_OK Return this if the processing within this function was successful
SW_FAIL Return this if the processing within this function failed
See also:
SWPluginServerStruct, ISWServerData, ISWServerSettings, CleanupServer

SWRESULT CleanupServer SWPluginServerStruct pThisServer  ) 
 

Called whenever a server is deleted by the user or by Server Watch at shutdown (called for each server). This is where you handle the cleanup of any data or resources you created that were associated to this server.

Note:
If you created a structure or class and attached it to the pCustomData variable inside of the SWPluginServerStruct, you need to cleanup that memory here.
Parameters:
pThisServer A SWPluginServerStruct that contains the information related to this server.
Return values:
SW_OK Return this if the processing within this function was successful
SW_FAIL Return this if the processing within this function failed
See also:
SWPluginServerStruct, ISWServerData, ISWServerSettings, InitServer

SWRESULT Ping SWPluginServerStruct pThisServer  ) 
 

Called whenever the user presses the "Update" button or when the data is update automatically in monitor mode. This is where you should update the associated ISWServerData class with the servers current status information.

This function is always called in its own thread. This is a critical aspect of the Server Watch plugin API. If we did not do this, the Server Watch GUI would pause everytime that a ping took longer to perform than several milliseconds (which is common during ping). In this special case you will not need to call Retain() or Release() on either ISWServerData or ISWServerSettings because the API has already performed those calls for you (calling them a second time, however, shouldn't hurt anything).

Parameters:
pThisServer A SWPluginServerStruct that contains the information related to this server.
Return values:
SW_OK Return this if the processing within this function was successful
SW_FAIL Return this if the processing within this function failed
See also:
ISWServerData, ISWServerSettings

SWRESULT JoinServer SWPluginServerStruct pThisServer  ) 
 

Called whenever the user attempts to join a server. You should process the join data in ISWServerSettings and call the application that will connect to the server.

This function can only be called if DoYouSupport() returns true when queried about JOIN support.

Parameters:
pThisServer A SWPluginServerStruct that contains the information related to this server.
Return values:
SW_OK Return this if the processing within this function was successful
SW_FAIL Return this if the processing within this function failed

SWRESULT CreateMenu SWPluginServerStruct pThisServer,
ISWPluginMenu pPluginMenu
 

Called whenever Server Watch needs to display a context menu.

When an operation that can trigger plugin custom action is triggered, this function is called to allow the plugin to provide Server Watch with a menu definition for the menu corresponding to the current action context.

Parameters:
pThisServer An SWPluginServerStruct that contains the information related to this server.
pPluginMenu An ISWPluginMenu used to retrieve context information for the menu, as well, as the interface to create menu items in the menu.
Return values:
SW_OK Return this if the processing within this function was successful
SW_FAIL Return this if the processing within this function failed


Copyright (c) 2003-2004, Deep Fried Software. All rights reserved.